home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-04 / xlib03.zip / XLIBREF.DOC < prev    next >
Text File  |  1993-04-05  |  54KB  |  1,627 lines
  1. -----------------------------------------------------------------------------
  2.  
  3.  
  4.  
  5.   *********      XLIB - Mode X graphics library           ****************
  6.   *********                                               ****************
  7.   ********* Written By Themie Gouthas                     ****************
  8.   ********* Aeronautical Research Laboratory              ****************
  9.   ********* Defence Science and Technology Organisation   ****************
  10.   ********* Australia                                     ****************
  11.   *********                                               ****************
  12.   ********* egg@dstos3.dsto.gov.au                        ****************
  13.   ********* teg@bart.dsto.gov.au                          ****************
  14.  
  15.  
  16.       Some of the code in this library has been contributed by :
  17.  
  18.                Matthew MacKenzie - matm@eng.umd.edu
  19. -----------------------------------------------------------------------------
  20.  
  21. DISCLAIMER
  22.  
  23.  This library is distributed AS IS. The author/s specifically disclaim
  24.  any responsibility for any loss of profit or any incidental, consequen-
  25.  tial or other damages.
  26.  
  27. ---------------------------------------------------------------------------
  28. INTRODUCTION
  29. ---------------------------------------------------------------------------
  30.  
  31. XLIB is a "user supported freeware" graphics library specifically designed
  32. with game programming in mind.
  33.  
  34. It has been placed in the public domain for the benefit of all, and
  35. represents MANY hours of work so it is requested that all users comply
  36. with the the wishes of the author/s as specified in the individual modules
  37. and:
  38. a) To leave the code in the public domain
  39. b) Not distribute any modified versions of this library
  40.  
  41. New contribution and comments are welcome and hopefully there will be
  42. more releases as the code evolves.
  43.  
  44. Finally, do not trust this excuse for a manual if in doubt. The place to get
  45. the answers is in the code itself.
  46.  
  47. REQUIREMENTS
  48.  
  49. Minimum requirements
  50.         286 processor,
  51.     Turbo C 2.0 or higher, or BORLANDC
  52.     MAKE  2.0 or higher
  53.     TLIB  2.0 or higher
  54.     Turbo Assembler 1.01 or higher
  55.  
  56.  
  57. GENERAL FEATURES
  58.  
  59.    Support for a number of 256 colour tweaked graphics mode resolutions
  60.    320x200 320x240 360x200 360x240 320x400 320x480 360x400 360x480
  61.  
  62.    Virtual screens larger than the physical screen (memory
  63.    permitting) that can be panned at pixel resolution in all directions
  64.  
  65.    A split screen capability for status displays etc.
  66.  
  67.    Text functions supporting 8x8 and 8x14 ROM fonts and user defined fonts
  68.  
  69.    Support for page flipping
  70.  
  71.    Graphics primitives such as line and rectangle drawing functions and
  72.    of course bit block manipulation functions
  73.  
  74.  
  75. MODULES COMPRISING XLIB
  76.    XMAIN    - Main module containig mode setting code and basic functions
  77.    XPOINT   - Pixel functions
  78.    XRECT    - Filled Rectangle and VRAM to VRAM block move functions
  79.    XPAL     - Palette functions
  80.    XLINE    - Line Functions
  81.    XTEXT    - Text and Font Functions
  82.    XPRINTF  - Printf style string output
  83.    XPBITMAP - Planar Bitmap functions
  84.    XCBITMAP - Compiled Bitmap functions
  85.  
  86.  
  87.  
  88. -------------------------------------------------------------------------
  89. BUILDING THE LIBRARIES
  90. -------------------------------------------------------------------------
  91.  
  92. Building the library had been made simple through the use of make.
  93.  
  94. To build and examples for one of the two models:
  95.  
  96. a) edit the makefile for the apropriate model (see note in the makefile)
  97. b) edit the makefile for the apropriate compiler (again see note in the
  98.    makefile)
  99. c) type "make" at the dos prompt.
  100.  
  101. It should be as simple as that. If problems are encountered then check
  102. to see if tasm, make, tlib, link and bcc (or tcc) are withinin your path.
  103. If not either change your path or specify the full path for these programs
  104. in the makefile. It is preferrable to have your path set correctly.
  105.  
  106.  
  107. Individual Compilation
  108. ----------------------
  109.  
  110. each ASM module can be compiled with the following commandline:
  111.  
  112. tasm /ml /d<model> <asm module name>
  113.  
  114. where <model> is s or l. Note the small model library can be used with
  115. compact model programs. Similarly the large model library can be used with
  116. medium model programs.
  117.  
  118. The resulting libraries are:
  119.  
  120.   xlib<version>s.lib    - small model library
  121.   xlib<version>l.lib    - large model library
  122.  
  123. To link the library with your programs just include the paropriate .lib
  124. file in your project file or on the BCC or TCC command line.
  125.  
  126.  
  127. Using the library with your programs
  128. --------------------------------------
  129.  
  130. Using the XLIB library in your programs is simple. Knowing the particular
  131. modules you require, just include the associated header files in your program
  132. and link your program modules with the library. If you don't want to wory
  133. about selecting the apropriate header file then just include "XLIB_ALL.H"
  134. which automatically includes all XLIB header files in your program.
  135.  
  136. For example compilations see the supplied makefile.
  137.  
  138. --------------------------------------------------------------------------
  139. GLOBAL DEFINES (xlib.inc)
  140. --------------------------------------------------------------------------
  141.  
  142. Types
  143.  
  144.  BYTE unsigned char
  145.  WORD unsigned int
  146.  
  147.  
  148. Available X mode resolutions
  149.  
  150.  X_MODE_320x200  0
  151.  X_MODE_320x240  1
  152.  X_MODE_360x200  2
  153.  X_MODE_360x240  3
  154.  X_MODE_320x400  4
  155.  X_MODE_320x480  5
  156.  X_MODE_360x400  6
  157.  X_MODE_360x480  7
  158.  
  159.  
  160. Palette rotation direction directiion
  161.  
  162.  BACKWARD 0
  163.  FORWARD  1
  164.  
  165.  
  166.  X_MODE_INVALID -1
  167.  ERROR           1
  168.  OK              0
  169.  
  170.  
  171. --------------------------------------------------------------------------
  172. MODULE XMAIN
  173. --------------------------------------------------------------------------
  174.  
  175. The Xmain module is the base module of the XLIB library. It contains the
  176. essential functions that initialize and customize the graphic environment.
  177.  
  178.  
  179. ASM SOURCES
  180.  
  181.    xmain.asm xmain.inc xlib.inc model.inc
  182.  
  183. C HEADER FILE
  184.  
  185.    xlib.h
  186.  
  187. EXPORTED VARIABLES
  188.  
  189.   NOTE: All variables are read only. I you modify them the results may
  190.   be unpredictable.
  191.  
  192.   InGraphics -  BYTE -  Flag indicating that the xlib graphics system is
  193.        active. Set by function "x_set_mode".
  194.  
  195.   CurrXMode - WORD - If the xlib graphics system is active, contains the id
  196.        of the x mode. Set by function "x_set_mode".
  197.        See also defines (ie X_MODE_320x200 ... )
  198.  
  199.   ScrnPhysicalByteWidth - WORD - Physical screen width in bytes. Set by
  200.        function "x_set_mode"
  201.  
  202.   ScrnPhysicalPixelWidth - WORD - Physical screen width in pixels. Set by
  203.        function "x_set_mode"
  204.  
  205.   ScrnPhysicalPixelHeight - WORD - Physical screen height in pixels. Set by
  206.        function "x_set_mode".
  207.  
  208.   ErrorValue - WORD - Contains error value. General use variable to
  209.        communicate the error status from several functions. The value
  210.        in this variable usually is only valid for the the last
  211.        function called that sets it.
  212.  
  213.   SplitScrnOffs - WORD - Offset in video ram of split screen. Set by
  214.        function "x_set_splitscrn". The value is only valid if a split
  215.        screen is active. See also global variable "SplitScrnActive".
  216.  
  217.   SplitScrnScanLine - WORD - Screen Scan Line the Split Screen starts at
  218.        initially when set by function "x_set_splitscrn". The value is only
  219.        valid if a split screen is active. See also global variable
  220.        "SplitScrnActive".This variable is not updated by "x_hide_splitscrn",
  221.        "x_adjust_splitscrn".
  222.  
  223.   SplitScrnVisibleHeight - WORD - The number of rows of the initial split
  224.        screen which are currently displayed. Modified by "x_hide_splitscrn",
  225.        "x_adjust_splitscrn" and "x_show_splitscrn".
  226.  
  227.   Page0_Offs - WORD - Offset in video ram of main virtual screen. Initially
  228.        set by function "x_set_mode" but is updated by functions
  229.        "x_set_splitscrn" and "x_set_doublebuffer".
  230.  
  231.   Page1_Offs - WORD - Offset in video ram of second virtual screen. Set by
  232.        and only is valid after a call to "x_set_doublebuffer".
  233.  
  234.   ScrnLogicalByteWidth - WORD - Virtual screen width in bytes. Set by
  235.        function "x_set_mode".
  236.  
  237.   ScrnLogicalPixelWidth - WORD - Virtual screen width in pixels. Set
  238.        by function "x_set_mode".
  239.  
  240.   ScrnLogicalHeight - WORD - Virtual screen height in pixels. Set
  241.        initially by function "x_set_mode" but is updated by functions
  242.        "x_set_splitscrn" and "x_set_doublebuffer".
  243.  
  244.   MaxScrollX - WORD - Max X pixel position of physical screen within
  245.        virtual screen. Set by function "x_set_mode".
  246.  
  247.   MaxScrollY - WORD - Max Y position of physical screen within virtual
  248.        screen. Set initially by function "x_set_mode" but is updated by
  249.        functions "x_set_splitscrn" and "x_set_doublebuffer".
  250.  
  251.   DoubleBufferActive - WORD - Indicates whether double-buffering is on. Set
  252.        by function "x_set_doublebuffer".
  253.  
  254.   VisiblePageIdx - WORD - Index number of current visible page. Initially
  255.        set by function "x_set_doublebuffer" but is updated by "x_page_flip".
  256.        This variable is only used while double buffering is on.
  257.  
  258.   HiddenPageOffs - WORD - Offset of hidden page. Initially set by function
  259.        "x_set_doublebuffer" but is updated by "x_page_flip". This variable
  260.        is only used while double buffering is on.
  261.  
  262.   VisiblePageOffs - WORD - Offset of visible page. Initially set by function
  263.        "x_set_doublebuffer" but is updated by "x_page_flip". This variable
  264.        is only used while double buffering is on.
  265.  
  266.   NonVisual_Offs - WORD - Offset of first byte of non-visual ram, the ram
  267.        that is available for bitmap storage etc. Set initially by function
  268.        "x_set_mode" but is updated by functions "x_set_splitscrn" and
  269.        "x_set_doublebuffer".
  270.  
  271.  
  272. EXPORTED FUNCTIONS
  273.  
  274.  
  275.   x_set_mode
  276.   ----------
  277.     C Prototype:  extern WORD x_set_mode(WORD mode,WORD WidthInPixels);
  278.  
  279.      mode          - The required mode as defined by the "Available X Mode
  280.                      resolutions" set of defines in the xlib.h header file.
  281.      WidthInPixels - The required virtual screen width.
  282.      Returns       - The actual width in pixels of the allocated virtual
  283.                      screen
  284.  
  285.   This function initialises the graphics system, setting the apropriate
  286.   screen resolution and allocating a virtual screen. The virtual screen
  287.   allocated may not necessarily be of the same size as specified in the
  288.   "WidthInPixels" parameter as it is rounded down to the nearest
  289.   multiple of 4.
  290.  
  291.   The function returns the actual width of the allocated virtual screen
  292.   in pixels if a valid mode was selected otherwise returns
  293.   X_MODE_INVALID.
  294.  
  295.   Saves virtual screen pixel width in "ScrnLogicalPixelWidth".
  296.   Saves virtual screen byte  width in "ScrnLogicalByteWidth".
  297.   Physical screen dimensions are set in "ScrnPhysicalPixelWidth".
  298.   "ScrnPhysicalByteWidth" and "ScrnPhysicalHeight". Other global
  299.   variables set are "CurrXMode","MaxScrollX", "MaxScrollY",
  300.   "InGraphics". The variable "SplitScrnScanline" is also initialized
  301.   to zero.
  302.  
  303.   See also:
  304.      Available X Mode resolutions
  305.      What is Mode X
  306.  
  307.   x_select_default_plane
  308.   ----------------------
  309.  
  310.     C Prototype:  void x_select_default_plane(BYTE plane);
  311.  
  312.     Enables default Read/Write access to a specified plane
  313.  
  314.  
  315.   x_set_splitscreen
  316.   -----------------
  317.  
  318.     C Prototype:  extern void x_set_splitscreen(WORD line);
  319.  
  320.     line - The starting scan line of the required split screen.
  321.  
  322.   This function activates Mode X split screen and sets starting scan
  323.   line. The split screen resides on the bottom half of the screen and has
  324.   a starting address of A000:0000 in video RAM.
  325.  
  326.   It also Updates Page0_Offs to reflect the existence of the split screen
  327.   region ie "MainScrnOffset" is set to the offset of the first pixel
  328.   beyond the split screen region. Other variable set are "Page1_Offs" which
  329.   is set to the same value as "Page0_Offs" (see graphics call sequence
  330.   below), "ScrnLogicalHeight","ScrnPhysicalHeight", "SplitScrnScanLine" and
  331.   "MaxScrollY".
  332.  
  333.   This function cannot be called after double buffering has been activated,
  334.   it will return an error. To configure your graphics environment the
  335.   sequence of graphics calls is as follows although either or both steps b
  336.   and c may be omitted:
  337.     a) x_set_mode
  338.     b) x_set_splitscreen
  339.     c) x_set_doublebuffer
  340.   Thus when you call this function successfully, double buffering is not
  341.   active so "Page1_Offs" is set to the same address as "Page0_Offs".
  342.  
  343.   WARNING: If you use one of the high resolution modes (360x480 as an
  344.     extreme example) you may not have enough video ram for split screen
  345.     and double buffering options since VGA video RAM is restricted to
  346.     64K.
  347.  
  348.   See Also:
  349.     What is a Split Screen ?
  350.     What is double buffering ?
  351.  
  352.  
  353.   x_set_doublebuffer
  354.   ------------------
  355.  
  356.   C Prototype: extern WORD x_set_doublebuffer(WORD PageHeight);
  357.  
  358.   PageHeight - The height of the two double buffering virtual screens.
  359.   Returns    - The closest possible height to the specified.
  360.  
  361.   This function sets up two double buffering virtual pages. 'ErrorValue"
  362.   is set according to the success or failure of this command.
  363.  
  364.   Other variables set are:
  365.  
  366.     _Page1_Offs           Offset of second virtual page
  367.     _NonVisual_Offs          Offset of first non visible video ram byte
  368.     _DoubleBufferActive      Flag
  369.     _PageAddrTable           Table of Double buffering pages start offsets
  370.     _ScrnLogicalHeight       Logical height of the double buffering pages
  371.     _MaxScrollY              Max vertical start address of physical screen
  372.                              within the virtual screen
  373.  
  374.   WARNING: If you use one of the high resolution modes (360x480 as an
  375.     extreme example) you may not have enough video ram for split screen
  376.     and double buffering options since VGA video RAM is restricted to
  377.     64K.
  378.  
  379.   See Also:
  380.     What is double buffering ?
  381.  
  382.   x_hide_splitscreen
  383.   ------------------
  384.  
  385.   C Prototype: extern void x_hide_splitscreen(void);
  386.  
  387.  
  388.   This function hides an existing split screen by setting its starting
  389.   scan line to the last physical screen scan line.
  390.   "ScreenPhysicalHeight" is adjusted but the "SplitScreenScanLine" is not
  391.   altered as it is required for restoring the split screen at a later stage.
  392.  
  393.   WARNING: Only to be used if SplitScrnLine has been previously called
  394.        Disabled for mode 4-7 (320x400-360x480). The memory for
  395.         the initial split screen is reserved and the size limitations
  396.        of these modes means any change in the split screen scan line
  397.            will encroach on the split screen ram
  398.            Update: Now disabled for these modes
  399.  
  400.  
  401.   See Also:
  402.  
  403.     What is a split screen ?
  404.  
  405.   x_show_splitscreen
  406.   ------------------
  407.  
  408.   C Prototype: extern void x_show_splitscreen(void);
  409.  
  410.   Restores split screen start scan line to the initial split screen
  411.   starting scan line as set by "SplitScrnScanLine".
  412.   "ScreenPhysicalHeight" is adjusted.
  413.  
  414.   WARNING: Only to be used if SplitScrnLine has been previously called
  415.        Disabled for mode 4-7 (320x400-360x480). The memory for
  416.         the initial split screen is reserved and the size limitations
  417.         of these modes means any change in the split screen scan line
  418.            will encroach on the split screen ram
  419.  
  420.  
  421.   x_adjust_splitscreen
  422.   --------------------
  423.  
  424.   C Prototype: extern void x_adjust_splitscreen(WORD line);
  425.  
  426.   line - The scan line at which the split screen is to start.
  427.  
  428.   Sets the split screen start scan line to a new scan line. Valid scan lines
  429.   are between the initial split screen starting scan line and the last
  430.   physical screen scan line. "ScreenPhysicalHeight" is also adjusted.
  431.  
  432.   WARNING: Only to be used if SplitScrnLine has been previously called
  433.        Disabled for mode 4-7 (320x400-360x480). The memory for
  434.         the initial split screen is reserved and the size limitations
  435.         of these modes means any change in the split screen scan line
  436.            will encroach on the split screen ram
  437.  
  438.  
  439.   x_set_start_addr
  440.   ----------------
  441.  
  442.   C Prototype: extern void x_set_start_addr(WORD X,WORD Y);
  443.  
  444.     X,Y - coordinates of top left corner of physical screen within current
  445.       virtual screen.
  446.  
  447.   Set Mode X non split screen physical start address within current virtual
  448.   page.
  449.  
  450.   X must not exceed (Logical screen width - Physical screen width)
  451.   ie "MaxScrollX" and Y must not exceed (Logical screen height -
  452.   Physical screen height) ie "MaxScrollY"
  453.  
  454.  
  455.   x_page_flip
  456.   -----------
  457.  
  458.   C Prototype: extern void x_page_flip(WORD X,WORD Y);
  459.  
  460.     X,Y - coordinates of top left corner of physical screen within the
  461.       the hidden virtual screen if double buffering is active, or
  462.       the current virtual screen otherwise.
  463.  
  464.   Sets the physical screen start address within currently hidden virtual
  465.   page and then flips pages. If double buffering is not active then this
  466.   function is functionally equivalent to "x_set_start_addr".
  467.  
  468.   X must not exceed (Logical screen width - Physical screen width)
  469.   ie "MaxScrollX" and Y must not exceed (Logical screen height -
  470.   Physical screen height) ie "MaxScrollY"
  471.  
  472.   x_text_mode
  473.   -----------
  474.  
  475.   C Prototype: extern void x_text_mode(void);
  476.  
  477.   Disables graphics mode.
  478.  
  479.  
  480.  
  481. --------------------------------------------------------------------------
  482. MODULE XPOINT
  483. --------------------------------------------------------------------------
  484.  
  485.   Point functions all MODE X 256 Color resolutions
  486.  
  487.   ASM SOURCES
  488.  
  489.     xpoint.asm xpoint.inc xlib.inc model.inc
  490.  
  491.   C HEADER FILE
  492.  
  493.    xpoint.h
  494.  
  495.   EXPORTED FUNCTIONS
  496.  
  497.   x_put_pix
  498.   ---------
  499.  
  500.   C Prototype: extern void x_put_pix(WORD X,WORD Y,WORD PageOffset,
  501.                                      WORD Color);
  502.  
  503.   Draw a point of specified colour at coordinates X,Y
  504.   within the virtual page starting at offset PageOffset.
  505.  
  506.  
  507.   x_get_pix
  508.   ---------
  509.  
  510.   C Prototype: extern WORD x_get_pix(WORD X, WORD Y, WORD PageBase);
  511.  
  512.   Read a point of at coordinates X,Y within the virtual page starting
  513.   at offset PageOffset.
  514.  
  515.  
  516. --------------------------------------------------------------------------
  517. MODULE XRECT
  518. --------------------------------------------------------------------------
  519.  
  520.   Screen rectangle display and manipulation functions
  521.  
  522.   ASM SOURCES
  523.  
  524.     xrect.asm xrect.inc xlib.inc model.inc
  525.  
  526.   C HEADER FILE
  527.  
  528.     xrect.h
  529.  
  530.  
  531.   EXPORTED FUNCTIONS
  532.  
  533.   x_rect_pattern
  534.   --------------
  535.  
  536.   C Prototype: extern void x_rect_pattern(WORD StartX, WORD StartY,
  537.                                           WORD EndX, WORD EndY,
  538.                                           WORD PageBase,BYTE far *Pattern);
  539.  
  540.   StartX,StartY - Coordinates of upper left hand corner of rectangle
  541.   EndX,EndY     - Coordinates of lower right hand corner of rectangle
  542.   PageBase      - Offset of virtual screen
  543.   *Pattern      - Pointer to the user defined pattern (16 bytes)
  544.  
  545.  
  546.   Mode X rectangle 4x4 pattern fill routine.
  547.  
  548.   Upper left corner of pattern is always aligned to a multiple-of-4
  549.   row and column. Works on all VGAs. Uses approach of copying the
  550.   pattern to off-screen display memory, then loading the latches with
  551.   the pattern for each scan line and filling each scan line four
  552.   pixels at a time. Fills up to but not including the column at EndX
  553.   and the row at EndY. No clipping is performed.
  554.  
  555.   Based on code originally published in DDJ Mag by M. Abrash
  556.  
  557.   Warning the VGA memory locations PATTERN_BUFFER (A000:FFFc) to
  558.   A000:FFFF are reserved for the pattern buffer
  559.  
  560.  
  561.   See Also:
  562.     Doctor Dobbs Journal references.
  563.  
  564.   x_rect_fill
  565.   ------------
  566.  
  567.   C Prototype: extern void x_rect_fill(WORD StartX,WORD StartY,
  568.                                        WORD EndX,WORD EndY,
  569.                                        WORD PageBase,WORD color);
  570.  
  571.   StartX,StartY - Coordinates of upper left hand corner of rectangle
  572.   EndX,EndY - Coordinates of lower right hand corner of rectangle
  573.   PageBase - Offset of virtual screen
  574.   Color -color to use for fill
  575.  
  576.   Mode X rectangle solid color fill routine.
  577.   Based on code originally published in DDJ Mag by M. Abrash
  578.  
  579.   See Also:
  580.     Doctor Dobbs Journal references.
  581.  
  582.   x_cp_vid_rect
  583.   --------------
  584.  
  585.   C Prototype: extern void x_cp_vid_rect(WORD SourceStartX,WORD SourceStartY,
  586.                           WORD SourceEndX,WORD SourceEndY,
  587.                           WORD DestStartX,WORD DestStartY,
  588.                           WORD SourcePageBase,WORD DestPageBase,
  589.                           WORD SourceBitmapWidth,WORD DestBitmapWidth);
  590.  
  591.   StartX,StartY- Coordinates of upper left hand corner of source rectangle
  592.   EndX,EndY    - Coordinates of lower right hand corner of source rectangle
  593.   DestStartX,DestStartY - Coordinates of rectangle destination
  594.   SourcePageBase        - source rectangle page offset
  595.   DestPageBase          - destination rectangles page offset
  596.   SourceBitmapWidth     - width of bitmap within the source virtual screen
  597.                           containing the source rectangle
  598.   DestBitmapWidth       - width of bitmap within the dest. virtual screen
  599.                           containing the destination rectangle
  600.  
  601.   Mode X display memory to display memory copy
  602.   routine. Left edge of source rectangle modulo 4 must equal left edge
  603.   of destination rectangle modulo 4. Works on all VGAs. Uses approach
  604.   of reading 4 pixels at a time from the source into the latches, then
  605.   writing the latches to the destination. Copies up to but not
  606.   including the column at SrcEndX and the row at SrcEndY. No
  607.   clipping is performed. Results are not guaranteed if the source and
  608.   destination overlap.
  609.  
  610.  
  611.   Based on code originally published in DDJ Mag by M. Abrash
  612.  
  613.   See Also:
  614.     Doctor Dobbs Journal references.
  615.  
  616. ---------------------------------------------------------------------------
  617. MODULE XPAL
  618. ---------------------------------------------------------------------------
  619.  
  620.     Palette functions for VGA 256 color modes.
  621.  
  622.     All the functions in this module operate on two variations of the
  623.     pallete buffer, the raw and annotated buffers.
  624.  
  625.     All those functions ending in "raw" operate on the following palette
  626.     structure:
  627.  
  628.        BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn
  629.  
  630.     No reference to the starting colour index or number of colours stored
  631.     is contained in the structure.
  632.  
  633.     All those functions ending in "struc" operate on the following palette
  634.     structure:
  635.  
  636.        BYTE:c,BYTE:n,BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn
  637.  
  638.     where c is the starting colour and n is the number of colours stored
  639.  
  640.  
  641.     WARNING: There is no validity checking in these functions. The onus is
  642.     on the user to supply valid parameters to the functions.
  643.  
  644.  
  645.   ASM SOURCES
  646.  
  647.     xpal.asm xpal.inc xlib.inc model.inc
  648.  
  649.   C HEADER FILE:
  650.  
  651.     xpal.h
  652.  
  653.   EXPORTED FUNCTIONS
  654.  
  655.   x_get_pal_raw
  656.   -------------
  657.  
  658.   C Prototype: extern void x_get_pal_raw(BYTE far * pal,WORD num_colrs,
  659.                                          WORD start_index);
  660.  
  661.   Read DAC palette into raw buffer with interrupts disabled
  662.   ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn
  663.  
  664.   WARNING: Memory for the palette buffers must all be pre-allocated.
  665.  
  666.   x_get_pal_struc
  667.   ---------------
  668.  
  669.   C Prototype: extern void x_get_pal_struc(BYTE far * pal,WORD num_colrs,
  670.                                               WORD start_index);
  671.  
  672.   Read DAC palette into annotated type buffer with interrupts disabled
  673.   ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn
  674.  
  675.   WARNING: memory for the palette buffers must all be pre-allocated
  676.  
  677.   x_put_pal_raw
  678.   -------------
  679.  
  680.   C Prototype: extern void x_put_pal_raw(BYTE far * pal,WORD num_colrs,
  681.                                          WORD start_index);
  682.  
  683.   Write DAC palette from raw buffer with interrupts disabled
  684.   ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn
  685.  
  686.   x_put_pal_struc
  687.   --------------
  688.  
  689.   C Prototype: extern void x_put_pal_struc(BYTE far * pal);
  690.  
  691.   Write DAC palette from annotated type buffer with interrupts disabled
  692.   ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn
  693.  
  694.   x_set_rgb
  695.   ---------
  696.  
  697.   C Prototype: extern x_set_rgb(BYTE color,BYTE red_c,BYTE green_c,
  698.                                BYTE blue_c);
  699.  
  700.   Set the RGB components of a vga color
  701.  
  702.   x_rot_pal_struc
  703.   ---------------
  704.  
  705.   C Prototype: extern void x_rot_pal_struc(BYTE far * pal,WORD direction);
  706.  
  707.   Rotate annotated palette buffer entries. Direction 0 = backward,
  708.   1 = forward.
  709.  
  710.   x_rot_pal_raw
  711.   -------------
  712.  
  713.   C Prototype: extern x_rot_pal_raw(BYTE far * pal,WORD direction,
  714.                                     WORD num_colrs);
  715.  
  716.   Rotate a raw palette buffer. Direction 0 = backward,
  717.   1 = forward.
  718.  
  719.   x_put_contrast_pal_struc
  720.   ------------------------
  721.  
  722.   C Prototype: extern  void x_put_contrast_pal_struc(BYTE far * pal,
  723.                BYTE  intensity);
  724.  
  725.   Write DAC palette from annotated type buffer with specified intensity
  726.   adjustment (ie palette entries are decremented where possible by
  727.   "intensity" units).
  728.  
  729.   Designed for fading in or out a palette without using an intermediate
  730.   working palette buffer ! (Slow but memory efficient ... OK for small
  731.   pal strucs}
  732.  
  733.  
  734.   x_transpose_pal_struc
  735.   ---------------------
  736.  
  737.   C Prototype: extern void x_transpose_pal_struc(BYTE far * pal,
  738.                                                  WORD StartColor);
  739.  
  740.   Write DAC palette from annotated type buffer with interrupts disabled
  741.   starting at a new palette index.
  742.  
  743.  
  744.   x_cpcontrast_pal_struc
  745.   ----------------------
  746.  
  747.   C Prototype: extern WORD x_cpcontrast_pal_struc(BYTE far *src_pal,
  748.                                 BYTE far *dest_pal,BYTE Intensity);
  749.  
  750.   Copy one annotated palette buffer to another making the intensity
  751.   adjustment. Used in fading in and out fast and smoothly.
  752.  
  753. ---------------------------------------------------------------------------
  754. MODULE XLINE
  755. ---------------------------------------------------------------------------
  756.  
  757.   Line Drawing functions.
  758.  
  759.   ASM SOURCES
  760.  
  761.     xline.asm xline.inc xlib.inc model.inc
  762.  
  763.   C HEADER FILE
  764.  
  765.     xline.h
  766.  
  767.   EXPORTED FUNCTIONS
  768.  
  769.   x_line
  770.   ------
  771.  
  772.   C Prototype: extern void x_line(WORD x0,WORD y0,WORD x1,WORD y1,
  773.                                   WORD color,WORD PageBase);
  774.  
  775.   Draw a line with the specified end points in the page starting at
  776.   offset "PageBase".
  777.  
  778.   No Clipping is performed.
  779.  
  780. ---------------------------------------------------------------------------
  781. MODULE XTEXT
  782. ---------------------------------------------------------------------------
  783.  
  784.   ASM SOURCES
  785.  
  786.     xtext.asm xtext.inc xlib.inc model.inc
  787.  
  788.   C HEADER FILE
  789.  
  790.     xtext.h
  791.  
  792.   DEFINES
  793.  
  794.    FONT_8x8  0
  795.    FONT_8x15 1
  796.    FONT_USER 2
  797.  
  798.   EXPORTED VARIABLES
  799.  
  800.     NOTE: All variables are read only. I you modify them the results may
  801.     be unpredictable.
  802.  
  803.     CharHeight - BYTE - Height of current inbuilt character set
  804.  
  805.     CharWidth  - BYTE - Width of current inbuilt character set
  806.  
  807.     FirstChar  - BYTE - First character of current inbuilt character set
  808.  
  809.     UserCharHeight - BYTE - Height of current user character set
  810.  
  811.     UserCharWidth - BYTE - Width of current user character set
  812.  
  813.     UserFirstCh - BYTE - First character of current user character set
  814.  
  815.  
  816.   EXPORTED FUNCTIONS
  817.  
  818.   x_text_init
  819.   -----------
  820.  
  821.   C Prototype: extern WORD x_text_init(void);
  822.  
  823.   Initializes the Mode X text driver and sets the default font (VGA ROM 8x8)
  824.  
  825.   x_set_font
  826.   ----------
  827.  
  828.   C Prototype: extern void x_set_font(WORD FontId);
  829.  
  830.   Select the working font where 0 = VGA ROM 8x8, 1 = VGA ROM 8x14
  831.   2 = User defined bitmapped font.
  832.  
  833.   WARNING: A user font must be registered before setting FontID 2
  834.  
  835.   See Also:
  836.  
  837.     Defines for this module
  838.  
  839.   x_register_userfont
  840.   -------------------
  841.  
  842.   C Prototype: extern void x_register_userfont(char far *UserFontPtr);
  843.  
  844.  
  845.   Register a user font for later selection. Only one user font can be
  846.   registered at any given time. Registering a user font deregisters the
  847.   previous user font. User fonts may be at most 8 pixels wide.
  848.  
  849.   USER FONT STRUCTURE
  850.  
  851.   Word:  ascii code of first char in font
  852.   Byte:  Height of chars in font
  853.   Byte:  Width of chars in font
  854.   n*h*Byte: the font data where n = number of chars and h = height
  855.       of chars
  856.  
  857.   WARNING: The onus is on the program to ensure that all characters
  858.            drawn whilst this font is active, are within the range of
  859.            characters defined.
  860.  
  861.   x_put_char
  862.   ----------
  863.  
  864.   C Prototype: extern void x_put_char(char ch,WORD X,WORD Y,WORD PgOffs,
  865.                                       WORD Color);
  866.  
  867.   Draw a text character at the specified location with the specified
  868.   color.
  869.  
  870.   ch       -  char to draw
  871.   x,y      -  screen coords at which to draw ch
  872.   ScrnOffs -  Starting offset of page on whih to draw
  873.   Color    -  Color of the text
  874.  
  875.   WARNING: InitTextDriver must be called before using this function
  876.  
  877.  
  878.   **** NOTE ****
  879.  
  880.   The file "xprintf.c" implements a printf style formatted output function
  881.  
  882.   x_printf
  883.   --------
  884.  
  885.   C Prototype: void x_printf(int x,int y,unsigned ScrnOffs,int color,
  886.                char *ln,...);
  887.  
  888.   x,y      -  screen coords at which to draw ch
  889.   ScrnOffs -  Starting offset of page on whih to draw
  890.   Color    -  Color of the text
  891.  
  892.   Parameters beyond Color conform to the standard printf parameters.
  893.  
  894.   x_bgprintf
  895.   ----------
  896.  
  897.   C Prototype: void x_bgprintf(int x,int y,unsigned ScrnOffs,int fgcolor,
  898.            int bgcolor, char *ln,...);
  899.  
  900.   x,y      -  screen coords at which to draw ch
  901.   ScrnOffs -  Starting offset of page on whih to draw
  902.   fgcolor    -  Color of the text foreground
  903.   bgcolor    -  Color of the text background
  904.  
  905.   Parameters beyond bgolor conform to the standard printf parameters.
  906.  
  907.  
  908. --------------------------------------------------------------------------
  909. MODULE XPBITMAP
  910. --------------------------------------------------------------------------
  911.  
  912.   This module implements a set of functions to operate on planar bitmaps.
  913.   Planar bitmaps as used by these functions have the following structure:
  914.  
  915.   BYTE 0                 The bitmap width in bytes (4 pixel groups) range 1..255
  916.   BYTE 1                 The bitmap height in rows range 1..255
  917.   BYTE 2..n1             The plane 0 pixels width*height bytes
  918.   BYTE n1..n2            The plane 1 pixels width*height bytes
  919.   BYTE n2..n3            The plane 2 pixels width*height bytes
  920.   BYTE n3..n4            The plane 3 pixels width*height bytes
  921.  
  922.   These functions provide the fastest possible bitmap blts from system ram to
  923.   to video and further, the single bitmap is applicable to all pixel
  924.   allignments. The masked functions do not need separate masks since all non
  925.   zero pixels are considered to be masking pixels, hence if a pixel is 0 the
  926.   corresponding screen destination pixel is left unchanged.
  927.  
  928.  
  929.   ASM SOURCES
  930.  
  931.     xpbitmap.asm xpbitmap.inc xlib.inc model.inc
  932.  
  933.   C HEADER FILE
  934.  
  935.     xpbitmap.h
  936.  
  937.   EXPORT FUNCTIONS
  938.  
  939.   x_put_masked_pbm
  940.   ----------------
  941.  
  942.   C Prototype: extern void x_put_masked_pbm(WORD X,WORD Y,WORD ScrnOffs,
  943.                  BYTE far * Bitmap);
  944.  
  945.   Mask write a planar bitmap from system ram to video ram. All zero source
  946.   bitmap bytes indicate destination byte to be left unchanged.
  947.  
  948.   Source Bitmap structure:
  949.  
  950.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  951.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  952.  
  953.   NOTE: width is in bytes ie lots of 4 pixels
  954.  
  955.   LIMITATIONS: No clipping is supported
  956.                Only supports bitmaps with widths which are a multiple of
  957.                4 pixels
  958.  
  959.   See Also: XBMTOOLS module for linear <-> planar bitmap conversion
  960.      functions.
  961.  
  962.   x_put_pbm
  963.   ---------
  964.  
  965.   C Prototype: extern void x_put_pbm(WORD X, WORD Y, WORD ScrnOffs,
  966.                  BYTE far * Bitmap);
  967.  
  968.   Write a planar bitmap from system ram to video ram.
  969.  
  970.   Source Bitmap structure:
  971.  
  972.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  973.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  974.  
  975.   NOTE: width is in bytes ie lots of 4 pixels
  976.  
  977.   LIMITATIONS: No clipping is supported
  978.                Only supports bitmaps with widths which are a multiple of
  979.                4 pixels
  980.  
  981.   FEATURES   : Automatically selects REP MOVSB or REP MOVSW  depending on
  982.                source bitmap width, by modifying opcode ;-).
  983.  
  984.   See Also: XBMTOOLS module for linear <-> planar bitmap conversion
  985.      functions.
  986.  
  987.   x_get_pbm
  988.   ---------
  989.  
  990.   C Prototype: extern void x_get_pbm(WORD X, WORD Y,BYTE Bw,BYTE Bh,
  991.                WORD ScrnOffs, BYTE far * Bitmap);
  992.  
  993.   Read a planar bitmap to system ram from video ram.
  994.  
  995.   Source Bitmap structure:
  996.  
  997.   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
  998.   Bitmap data (plane 2)..,Bitmap data (plane 3)..
  999.  
  1000.   NOTE: width is in bytes ie lots of 4 pixels
  1001.  
  1002.   LIMITATIONS: No clipping is supported
  1003.                Only supports bitmaps with widths which are a multiple of
  1004.                4 pixels
  1005.  
  1006.   FEATURES   : Automatically selects REP MOVSB or REP MOVSW  depending on
  1007.                source bitmap width, by modifying opcode ;-).
  1008.  
  1009.   See Also: XBMTOOLS module for linear <-> planar bitmap conversion
  1010.      functions.
  1011.  
  1012. --------------------------------------------------------------------------
  1013. MODULE  XCBITMAP
  1014. --------------------------------------------------------------------------
  1015.                                  XCBITMAP:
  1016.                The Care and Feeding of Compiled Masked Blits
  1017.                            by Matthew MacKenzie
  1018.  
  1019. This file describes the XCBITMAP module of the Xlib library, made up of
  1020. the files XCBITMAP.ASM, XCBITMAP.INC, XCBITMAP.H, and this file, XCBITMAP.DOC.
  1021.  
  1022. The XCBITMAP module is small, containing only two procedures:
  1023.   o  x_compile_bitmap compiles your bitmap into native code which writes
  1024.      to the VGA screen in an X mode.
  1025.   o  x_put_cbitmap converts X and Y coordinates into a location on the
  1026.      screen, sets up the necessary VGA registers, and executes the compiled
  1027.      bitmap as a subroutine.
  1028.  
  1029.     x_compile_bitmap scans through a source bitmap and generates 8086
  1030. instructions to plot every nonzero pixel.  It is designed to be used
  1031. before the action begins rather than on-the-fly.  The compiled bitmap
  1032. contains no branches, and no reference to the zero (transparent) pixels.
  1033. Where two pixels are exactly four columns apart they are plotted with a
  1034. single 16-bit store, and the VGA MAP_MASK register will be set at most
  1035. four times.  As a result your bitmap may run several times faster than a
  1036. traditional memory-to-VGA masked blit routine.
  1037.     There is no way to perform clipping on these bitmaps, or to plot a
  1038. pixel of color zero.
  1039.     x_compile_bitmap works with bitmaps in a very simple format, and does
  1040. not require the bitmap's width or height to be multiples of four, eight,
  1041. or even two.  While this makes it easier for us humans to design new
  1042. bitmaps, it does make the compilation relatively slow, on a time scale of
  1043. 60 frames per second.  Since a compiled bitmap is relocatable you may
  1044. just want to have it saved to disk, and not include the source bitmap
  1045. in your program at all.
  1046.     The source bitmap format is an array of bytes, like this:
  1047.  
  1048. char far * eye ={
  1049.          13,7,
  1050.          0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0,
  1051.                  0, 0, 9, 9, 1, 1, 1, 4, 4, 9, 9, 0, 0,
  1052.                  0, 9, 9, 1, 2, 0, 0, 4, 4, 1, 9, 9, 0,
  1053.                  9, 9, 9, 1, 0, 0, 0, 0, 1, 1, 9, 9, 9,
  1054.                  0, 9, 9, 1, 2, 0, 0, 2, 1, 1, 9, 9, 0,
  1055.                  0, 0, 9, 9, 1, 1, 1, 1, 1, 9, 9, 0, 0,
  1056.                  0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0};
  1057.  
  1058.     To compile this image for a mode 360 pixels (90 byte columns) across:
  1059. EyeSize = x_compile_bitmap(90, eye, CompiledEye);
  1060.     Both `eye' and `CompiledEye' are of type (char far *).  Notice that
  1061. both buffers must exist beforehand.  Since x_compile_bitmap returns the
  1062. size of the compiled code, in bytes, you can reallocate the bitmap
  1063. immediately to the right size.  The pointers are 32-bit because
  1064. compiled bitmaps take so much space: they are at one end of the speed-
  1065. versus-memory spectrum. You may, of course, still use a 16-bit memory
  1066. model, or your own allocation scheme, and cast the pointers to 32 bits
  1067. to compile or blit a bitmap.  A good rule of thumb is to allocate
  1068. (3.5 x buffer-height x buffer-width) + 25 bytes  (rounding up ;-),
  1069. then pare your bitmap down when you find out how much space you've
  1070. actually used.
  1071.     Since the compiled bitmap has to fit within one segment of memory, it
  1072. cannot contain more than about 19,000 pixels.  This will not be a
  1073. limitation for most sane programmers.  If you are not a sane programmer try
  1074. splitting your huge, unwieldy image up into smaller parts -- you can use
  1075. the same gigantic bitmap if you divide it into horizontal slices for
  1076. compilation.  For that matter, dividing the source up that way will let
  1077. you use a source bitmap large than 64K, which is an even sicker idea...
  1078.     Back to business.  A bitmap is compiled for only one width of screen.
  1079. If you are using a logical screen larger than your physical screen, call
  1080. the bitmap compiler with the logical width -- the important thing is the
  1081. number of bytes per line.  Notice that you do not have to be in a graphics
  1082. mode to use this routine.  This allows you to develop and compile bitmaps
  1083. separately, with whatever utility programs you might cook up.
  1084.  
  1085.     The second function is x_put_cbitmap.  To plot our eye at (99,4), on
  1086. the page which starts at location 0:
  1087. x_put_cbitmap(99, 4, 0, CompiledEye);
  1088.     This function depends on the global variable ScrnLogicalByteWidth from
  1089. the module XMAIN, which should be the same number as the column parameter
  1090. you used to compile your bitmap.
  1091.     The XCBITMAP module supports memory-to-VGA blits only.  Xlib also
  1092. includes non-masking routines which can quickly save and restore the
  1093. background screen behind your bitmap, using fast string operations.
  1094.  
  1095.    This module is part of the Xlib package, and is in the public domain.
  1096. If you write something which uses it, though, please send me a copy as a
  1097. courtesy -- if for no other reason so I can tilt my chair back and reflect
  1098. that it may have been worth the trouble after all.
  1099.  
  1100. The included program DEMO2.C demonstarates the performance difference
  1101. between planar bitmap masked blits and compiled bitmap blits.
  1102.  
  1103.  
  1104.   ASM SOURCES
  1105.  
  1106.      xcbitmap.asm xcbitmap.inc xlib.inc model.inc
  1107.  
  1108.   C HEADER FILE
  1109.  
  1110.      xcbitmap.h
  1111.  
  1112.   EXPORT FUNCTIONS
  1113.  
  1114.   x_compile_bitmap
  1115.   ----------------
  1116.  
  1117.   C Prototype: extern int x_compile_bitmap (WORD scrn_logical_width,
  1118.                    char far * bitmap,char far * output);
  1119.  
  1120.   Compile a linear bitmap to generate machine code to plot it
  1121.   at any required screen coordinates FAST. Faster than blits
  1122.   using planar bitmaps as in module XPBIITMAP
  1123.  
  1124.   The screen logical width is in bytes rather than pixels.
  1125.  
  1126.   The source linear bitmaps have the following structure:
  1127.  
  1128.   BYTE 0                 The bitmap width in pixels  range 1..255
  1129.   BYTE 1                 The bitmap height in rows   range 1..255
  1130.   BYTE 2..n              The width*height bytes of the bitmap
  1131.  
  1132.  
  1133.   All four main registers are totaled.
  1134.  
  1135.   See Also: XBMTOOLS module for linear <-> planar bitmap conversion
  1136.      functions.
  1137.  
  1138.   x_put_cbitmap
  1139.   -------------
  1140.  
  1141.   C Prototype: extern void x_put_cbitmap (WORD XPos,WORD YPos,
  1142.               WORD PageOffset,char far * CompiledBitmap);
  1143.  
  1144.   XPos,YPos   -  screen coords at which to draw bitmap
  1145.   PageOffs    -  Starting offset of page on whih to draw
  1146.   CompiledBitmap - pointer to compiled bitmap
  1147.  
  1148.   Displays a compiled bitmap generated by x_compile_bitmap at given
  1149.   coordinates, on a given screen page.
  1150.  
  1151.   See Also: XBMTOOLS module for linear <-> planar bitmap conversion
  1152.      functions.
  1153.  
  1154.  
  1155. --------------------------------------------------------------------------
  1156. MODULE XBMTOOLS
  1157. --------------------------------------------------------------------------
  1158.  
  1159.   This module implements a set of functions to convert between planar
  1160.   bitmaps and linear bitmaps.
  1161.  
  1162.   PLANAR BITMAPS
  1163.  
  1164.   Planar bitmaps as used by these functions have the following structure:
  1165.  
  1166.   BYTE 0                 The bitmap width in bytes (4 pixel groups) range 1..255
  1167.   BYTE 1                 The bitmap height in rows range 1..255
  1168.   BYTE 2..n1             The plane 0 pixels width*height bytes
  1169.   BYTE n1..n2            The plane 1 pixels width*height bytes
  1170.   BYTE n2..n3            The plane 2 pixels width*height bytes
  1171.   BYTE n3..n4            The plane 3 pixels width*height bytes
  1172.  
  1173.   as used by x_put_pbm, x_get_pbm, x_put_masked_pbm.
  1174.  
  1175.   LINEAR BITMAPS
  1176.  
  1177.   Linear bitmaps have the following structure:
  1178.  
  1179.   BYTE 0                 The bitmap width in pixels  range 1..255
  1180.   BYTE 1                 The bitmap height in rows   range 1..255
  1181.   BYTE 2..n              The width*height bytes of the bitmap
  1182.  
  1183.  
  1184.  
  1185.  
  1186.   ASM SOURCES
  1187.  
  1188.     xbmtools.asm xpbmtools.inc model.inc
  1189.  
  1190.   C HEADER FILE
  1191.  
  1192.     xbmtools.h
  1193.  
  1194.   EXPORT DEFINES
  1195.  
  1196.     BM_WIDTH_ERROR
  1197.  
  1198.   EXPORT FUNCTIONS
  1199.  
  1200.   x_pbm_to_bm
  1201.   ------------
  1202.   C Prototype:  extern int x_pbm_to_bm(char far * source_pbm,
  1203.                        char far * dest_bm);
  1204.  
  1205.   This function converts a bitmap in the planar format to the linear format
  1206.   as used by x_compile_bitmap.
  1207.  
  1208.   WARNING: the source and destination bitmaps must be pre - allocated
  1209.  
  1210.   NOTE: This function can only convert planar bitmaps that are suitable.
  1211.     If the source planar bitmap's width (per plane) is >= 256/4
  1212.     it cannot be converted. In this situation an error code
  1213.     BM_WIDTH_ERROR. On successful conversion 0 is returned.
  1214.  
  1215.   x_bm_to_pbm
  1216.   ------------
  1217.   C Prototype:  extern int x_bm_to_pbm(char far * source_pbm,
  1218.                        char far * dest_bm);
  1219.  
  1220.   This function converts a bitmap in the linear format as used by
  1221.   x_compile_bitmap to the planar formap.
  1222.  
  1223.   WARNING: the source and destination bitmaps must be pre - allocated
  1224.  
  1225.   NOTE: This function can only convert linear bitmaps that are suitable.
  1226.     If the source linear bitmap's width is not a multiple of 4
  1227.     it cannot be converted. In this situation an error code
  1228.     BM_WIDTH_ERROR. On successful conversion 0 is returned.
  1229.  
  1230. --------------------------------------------------------------------------
  1231. MODULE XDETECT
  1232. --------------------------------------------------------------------------
  1233.  
  1234.   This module implements a set of functions to detect the PC's hardware
  1235.   configuration.
  1236.  
  1237.   ASM SOURCES
  1238.  
  1239.     xdetect.asm xdetect.inc model.inc
  1240.  
  1241.   C HEADER FILE
  1242.  
  1243.     xdetect.h
  1244.  
  1245.   EXPORTED DEFINES
  1246.  
  1247.     I8086   0
  1248.     I80186  1
  1249.     I80286  2
  1250.     I80386  3
  1251.  
  1252.     NoGraphics 0
  1253.     MDA        1
  1254.     CGA        2
  1255.     EGAMono    3
  1256.     EGAColor   4
  1257.     VGAMono    5
  1258.     VGAColor   6
  1259.     MCGAMono   7
  1260.     MCGAColor  8
  1261.  
  1262.  
  1263.   EXPORT FUNCTIONS
  1264.  
  1265.  
  1266.   x_graphics_card
  1267.   ---------------
  1268.   C Prototype: extern int x_graphics_card();
  1269.  
  1270.   This function returns the type of graphics card installed. See defines
  1271.   above.
  1272.  
  1273.   x_processor
  1274.   -----------
  1275.   C Prototype: extern int x_processor();
  1276.  
  1277.   This function returns the type of processor installed. A 486 registers
  1278.   as a 386. See defines above.
  1279.  
  1280.  
  1281. --------------------------------------------------------------------------
  1282. MODULE XFILEIO
  1283. --------------------------------------------------------------------------
  1284.  
  1285.   Handle based file I/O functions.
  1286.  
  1287.   See any good DOS programming reference for more information on int 21h
  1288.   DOS services.
  1289.  
  1290.   ASM SOURCES
  1291.  
  1292.     xfileio.asm xfileio.inc model.inc
  1293.  
  1294.   C HEADER FILE
  1295.  
  1296.     xfileio.h
  1297.  
  1298.   EXPORTED DEFINES
  1299.  
  1300.   file access modes
  1301.  
  1302.     F_RDONLY
  1303.     F_WRONLY
  1304.     F_RDWR
  1305.  
  1306.   seek codes
  1307.  
  1308.     SEEK_START
  1309.     SEEK_CURR
  1310.     SEEK_END
  1311.  
  1312.   file error value
  1313.  
  1314.     FILE_ERR
  1315.  
  1316.   EXPORT FUNCTIONS
  1317.  
  1318.   f_open
  1319.   ------
  1320.   C Prototype: extern int f_open(char * filename, char access);
  1321.  
  1322.   Opens a file according to the access char:
  1323.  
  1324.     F_RDONLY = read only   - If doesnt exist return error
  1325.     F_WRONLY = write only  - If doesnt exist create it otherwise clear it
  1326.     F_RDWR   = read/write  - If doesnt exist create it
  1327.  
  1328.   Returns the file handle on success, FILE_ERR on failure
  1329.  
  1330.  
  1331.   f_close
  1332.   -------
  1333.  
  1334.   C Prototype:  extern int f_close(int handle);
  1335.  
  1336.   Closes the file associated with the specified handle
  1337.  
  1338.   Returns 0 on success, FILE_ERR on failure
  1339.  
  1340.  
  1341.   f_read
  1342.   ------
  1343.  
  1344.   C Prototype:  extern int f_read(int handle, char far * buffer, int count);
  1345.  
  1346.   Reads a block of count bytes from the file specified by the handle
  1347.   into the buffer
  1348.  
  1349.   Returns count on success, FILE_ERR on failure
  1350.  
  1351.  
  1352.   f_write
  1353.   -------
  1354.  
  1355.   C Prototype: extern int f_write(int handle, char far * buffer, int count);
  1356.  
  1357.   Writes a block of count bytes to the file specified by the handle
  1358.   from the buffer
  1359.  
  1360.   Returns count on success, FILE_ERR on failure
  1361.  
  1362.  
  1363.   f_seek
  1364.   ------
  1365.  
  1366.   C Prototype: extern long int f_seek(int handle, long int position,
  1367.                       char method_code)
  1368.  
  1369.   Moves the file pointer according to the position and method code
  1370.  
  1371.   Returns file pointer position on success, FILE_ERR on failure
  1372.  
  1373.  
  1374.   f_filelength
  1375.   ------------
  1376.  
  1377.   C Prototype:
  1378.  
  1379.     extern long int f_filelength(int handle)
  1380.  
  1381.   Returns the length of the file associated with the specified handle
  1382.  
  1383.   Returns file length on success, FILE_ERR on failure
  1384.  
  1385.  
  1386. --------------------------------------------------------------------------
  1387. MODULE XRLETOOL
  1388. --------------------------------------------------------------------------
  1389.  
  1390. This module implements a number of functions comprising an RLE encoding
  1391. decoding system.
  1392.  
  1393. RLE stands for RUN LENGTH ENCODING. It is a quick simple data compression
  1394. scheme which is commonly used for image data compression or compression
  1395. of any data. Although not the most efficient system, it is fast, which is
  1396. why it is used in image storage systems like PCX. This implementation is
  1397. more efficient than the one used in PCX files because it uses 1 bit to
  1398. identify a Run Length byte as opposed to two in PCX files, but more on this
  1399. later.
  1400.  
  1401. This set of functions can be used to implement your own compressed image
  1402. file format or for example compress game mapse for various levels etc.
  1403. The uses are limited by your imagination.
  1404.  
  1405. I opted for trading off PCX RLE compatibility for the improved compression
  1406. efficiency.
  1407.  
  1408. Here is how the data is un-compressed to give an idea of its structure.
  1409.  
  1410.  
  1411. STEP 1 read a byte from the RLE compressed source buffer.
  1412.  
  1413. STEP 2 if has its high bit is set then the lower 7 bits represent the number
  1414.        of times the next byte is to be repeated in the destination buffer.
  1415.        if the count (lower 7 bits) is zero then
  1416.       we have finished decoding goto STEP 5
  1417.        else goto STEP 4
  1418.  
  1419. STEP 3 Read a data from the source buffer and copy it directly to the
  1420.        destination buffer.
  1421.        goto STEP 1
  1422.  
  1423. STEP 4 Read a data from the source buffer and copy it to the destination
  1424.        buffer the number of times specified by step 2.
  1425.        goto STEP 1
  1426.  
  1427. STEP 5 Stop, decoding done.
  1428.  
  1429. If the byte does not have the high bit set then the byte itself is transfered
  1430.  to the destination buffer.
  1431.  
  1432. Data bytes that have the high bit already set and are unique in the input
  1433.  stream are represented as a Run Length of 1 (ie 81 which includes high bit)
  1434.  followed by the data byte.
  1435.  
  1436. If your original uncompressed data contains few consecutive bytes and most
  1437. have high bit set (ie have values > 127) then your so called
  1438. compressed data would require up to 2x the space of the uncompressed data,
  1439. so be aware that the compression ratio is extremely variable depending on the
  1440. type of data being compressed.
  1441.  
  1442. Apologies for this poor attempt at a description, but you can look up
  1443. RLE in any good text. Alternatively, any text that describes the PCX file
  1444. structure in any depth should have a section on RLE compression.
  1445.  
  1446.  
  1447.  
  1448.   ASM SOURCES
  1449.  
  1450.     xrletool.asm xrletool.inc model.inc
  1451.  
  1452.   C HEADER FILE
  1453.  
  1454.     xrletool.h
  1455.  
  1456.   EXPORTED DEFINES
  1457.  
  1458.  
  1459.   EXPORT FUNCTIONS
  1460.  
  1461.   x_buff_RLDecode
  1462.   ---------------
  1463.  
  1464.    Expands an RLE compresses source buffer to a destination buffer.
  1465.    returns the size of the resultant uncompressed data.
  1466.  
  1467.    C PROTOTYPE:
  1468.  
  1469.    extern unsigned int x_buff_RLDecode(char far * source_buff,
  1470.                       char far * dest_buff);
  1471.  
  1472.    source_buff   - The buffer to compress
  1473.    dest_buff     - The destination buffer
  1474.  
  1475.    WARNING: buffers must be pre allocated.
  1476.  
  1477.  
  1478.    x_buff_RLEncode
  1479.    ---------------
  1480.  
  1481.    RLE Compresses a source buffer to a destination buffer and returns
  1482.    the size of the resultant compressed data.
  1483.  
  1484.    C PROTOTYPE:
  1485.  
  1486.     extern unsigned int x_buff_RLEncode(char far * source_buff,
  1487.          char far * dest_buff,unsigned int count);
  1488.  
  1489.    source_buff   - The buffer to compress
  1490.    dest_buff     - The destination buffer
  1491.    count         - The size of the source data in bytes
  1492.  
  1493.    WARNING: buffers must be pre allocated.
  1494.  
  1495.    x_buff_RLE_size
  1496.    ---------------
  1497.  
  1498.    Returns the size the input data would compress to.
  1499.  
  1500.    C PROTOTYPE:
  1501.  
  1502.     extern unsigned int x_buff_RLE_size(char far * source_buff,
  1503.          unsigned int count);
  1504.  
  1505.    source_buff   - The uncompressed data buffer
  1506.    count         - The size of the source data in bytes
  1507.  
  1508.  
  1509.    x_file_RLEncode
  1510.    ---------------
  1511.  
  1512.    RLE Compresses a source buffer to an output file returning
  1513.    the size of the resultant compressed data or 0 if it fails.
  1514.  
  1515.    C PROTOTYPE:
  1516.  
  1517.    extern unsigned int x_file_RLEncode(int handle,
  1518.      char far * source_buff,unsigned int count);
  1519.  
  1520.    source_buff   - The buffer to compress
  1521.    handle        - The file handler
  1522.    count         - The size of the source data in bytes
  1523.  
  1524.    x_file_RLDecode
  1525.    ---------------
  1526.  
  1527.    Expands an RLE compresses file to a destination RAM buffer.
  1528.    returns the size of the resultant uncompressed data.
  1529.  
  1530.    C PROTOTYPE:
  1531.  
  1532.     extern unsigned int x_buff_RLDecode(int handle,
  1533.          char far * dest_buff);
  1534.  
  1535.    handle        - Input file handle
  1536.    dest_buff     - The destination buffer
  1537.  
  1538. --------------------------------------------------------------------
  1539. REFERENCE SECTION
  1540. --------------------------------------------------------------------
  1541.  
  1542.  
  1543. REFERENCES
  1544. ----------
  1545.  
  1546. In my opinion Doctor Dobbs Journal is the best reference text for
  1547. VGA Mode X graphics:
  1548.  
  1549. Issue 178 Jul 1991 : First reference to Mode X
  1550. Article Abstract   : VGA's undocumented Mode X supports page flipping,
  1551.              makes off screen memory available, has square pixels,
  1552.              and increases performance by as muck as 4 times.
  1553.  
  1554. Issue 179 Aug 1991 : Continuation
  1555. Article Abstract   : Michael discusses latches and VGA's undoccumented
  1556.              Mode X.
  1557.  
  1558. Issue 181 Sep 1991 : Continuation
  1559. Article Abstract   : Michael puts the moves on animation using VGA's 256
  1560.              colors.
  1561.  
  1562. Issue 184 Oct 1991 : First of a continuing series covering 3-D animation
  1563.              using VGA's Mode X. This series is still ongoing
  1564.              (October 1992)
  1565. Article Abstract   : Michael moves into 3-D animation, starting with basic
  1566.              polygon fills and page flips.
  1567.  
  1568.  
  1569. WHAT IS MODE X ?
  1570. ----------------
  1571.  
  1572. Mode X is a derrivative of the VGA's standard mode 13h (320x200 256 color).
  1573. It is a (family) of undocumented video modes that are created by tweaking
  1574. the VGA's registers. The beauty of mode X is that it offers several
  1575. benefits to the programmer:
  1576.  - Multiple graphice pages where mode 13h doesn't allowing for page flipping
  1577.    (also known as double buffering) and storage of images and data in
  1578.    offscreen video memory
  1579.  - A planar video ram organization which although more difficult to program,
  1580.    allows the VGA's plane-oriented hardware to be used to process pixels in
  1581.    parallel, improving performance by up to 4 times over mode 13h
  1582.  
  1583.    See issue 178-179 of D.D.J. for a full description of VGA's Mode X.
  1584.  
  1585. WHAT IS A SPLIT SCREEN ?
  1586. ------------------------
  1587.  
  1588. A split screen is a neat hardware feature offered by the EGA and VGA video
  1589. cards. A split screen is a mode of graphics operationin which the Hardware
  1590. splits the visual graphics screen horizontally and treats both halves as
  1591. individual screens each starting at different locations in video RAM.
  1592.  
  1593. The bottom half (which is usually referred to as the split screen) always
  1594. starts at address A000:0000 but the top half's starting address is user
  1595. definable.
  1596.  
  1597. The most common application of split screens in games is the status display
  1598. in scrolling games. Split screens make this sort of game simpler to program
  1599. because when the top half window is scrolled the programmer does not have to
  1600. worry about redrawing the bottom half.
  1601.  
  1602. WHAT IS DOUBLE BUFFERING ?
  1603. --------------------------
  1604.  
  1605. Double buffering (also known as page flipping) is the technique most often
  1606. used to do animation. it requires hardware that is capable of displaying
  1607. multiple graphics pages (or at least 2). Animation is achieved by drawing
  1608. an image in the non visible screen and then displaying the non visible
  1609. screen. Once te page has been flipped the process starts again. The next
  1610. frame of the animation is drawn on the non visible screen, the page is
  1611. flipped again etc.
  1612.  
  1613. iMode X is a derrivative of the VGA's standard mode 13h (320x200 256 color).
  1614. It is a (family) of undocumented video modes that are created by tweaking
  1615. the VGA's registers. The beauty of mode X is that it offers several
  1616. benefits to the programmer:
  1617.  - Multiple graphice pages where mode 13h doesn't allowing for page flipping
  1618.    (also known as double buffering) and storage of images and data in
  1619.    offscreen video memory
  1620.  - A planar video ram organization which although more difficult to program,
  1621.    allows the VGA's plane-oriented hardware to be used to process pixels in
  1622.    parallel, improving performance by up to 4 times over mode 13h
  1623.  
  1624.    Again see D.D.J. for an in depth discussion of animation using Mode X
  1625.  
  1626.  
  1627.